Release 10.1A: OpenEdge Development:
Programming Interfaces

Asserting the auditing identity

The 4GL mechanisms for asserting the auditing ID depend on how you authenticate and assert user IDs. These mechanisms include several 4GL elements, including:

The 4GL SETUSERID function, CONNECT statement, and the User ID (-U) and Password (-P) startup parameters used to authenticate and set database connection IDs using the OpenEdge internal authentication system (_User table).
The client-principal object used to represent and, together with a trusted authentication domain registry, validate an externally authenticated user ID as a database connection ID or Progress session ID.
The 4GL SET-DB-CLIENT function and the SET-CLIENT( ) method on the SECURITY-POLICY system handle used to assert and validate an externally authenticated user ID represented by a client-principal object.

The following sections describe the use of these elements in the context of auditing. For more information on using these mechanisms to assert user identities in application code, see Chapter 2, " Application Security."

This section describes the following basic application scenarios and the 4GL elements you can code to assert the auditing ID for a given audit-enabled database:

Using the database connection ID
Using the Progress session ID
Application design considerations

Using the database connection ID

When you configure auditing to use the database connection ID (the default), you enable each audit-enabled database to use a different auditing ID that is potentially authenticated to a different authentication system. You can use all of the following 4GL elements to assert the database connection ID as the auditing ID:

User ID (-U) and Password (-P) startup and connection parameters (at client startup or in the CONNECT statement), which authenticate and assert a connection ID from the database _User table.
SETUSERID function, which authenticates and asserts a connection ID to a connected database from the database _User table.
SET-DB-CLIENT statement, which asserts a user ID that is authenticated to a trusted domain registry (database- or application-defined, depending on your configuration) and asserts that ID as the connection ID for a specified connected database using a sealed client-principal object.
SECURITY-POLICY:SET-CLIENT( ) method, which asserts a user ID that is authenticated to a trusted domain registry (database- or application-defined, depending on your configuration) and asserts that ID as the connection ID for all connected databases that do not already have an explicitly set database connection ID using a sealed client-principal object.

If you set the database connection ID with one of the first three elements, using the SET-CLIENT( ) method has no effect on this setting. Whatever way you set the database connection ID, the act of doing so generates an appropriate audit event (if auditing is enabled), and the resulting database connection ID, for each database where auditing is enabled, becomes the auditing ID.

The configured auditing identity, itself, has no effect on database authorization. OpenEdge authorizes all run-time CAN* permissions and auditing privileges on a database, as well as database connections, using the database connection ID. So, when you take the default and specify the database connection ID as the auditing ID, it happens that the same user ID used to authorize database access is also associated with the audit event records generated in a given audit-enabled database.

Note: CAN* permissions refer to the permissions for modifying tables and fields that you can set for each user in the OpenEdge Data Administration tool or character-mode Data Dictionary. Auditing privileges refer to permissions to perform auditing operations. For more information on CAN* permissions settings, see OpenEdge Deployment: Managing 4GL Applications and Chapter 2, "Application Security," in this manual. For more information on auditing privileges, see the "Configuring auditing privileges" section.

Using the Progress session ID

When you configure auditing to use the Progress session ID as the auditing ID, you enable all audit-enabled databases so-configured to use a single auditing ID authenticated from a single authentication system. You can assert a single Progress session ID as the auditing ID using the SECURITY-POLICY:SET-CLIENT( ) method. This method asserts the Progress session ID to OpenEdge and validates it against the application trusted domain registry using a sealed client-principal object. Setting the Progress session ID does not, in itself, generate an audit event. The process of initiating and managing a client login session for an Progress session ID can, however, set several different auditing events. For more information, see the "Managing audit event context" section.

The configured auditing identity, itself, has no effect on database authorization. OpenEdge authorizes all run-time CAN* permissions and auditing privileges on a database, as well as database connections, using the database connection ID. When you use the Progress session ID as the auditing ID, the user ID (database connection ID) used to authorize database access and audit privileges might not have the same value as the user ID (Progress session ID) that is associated with the audit event records generated in a given audit-enabled database.

Note: CAN* permissions refer to the permissions for modifying tables and fields that you can set for each user in the OpenEdge Data Administration tool or character-mode Data Dictionary. Auditing privileges refer to permissions to perform auditing operations. For more information on CAN* permissions settings, see OpenEdge Deployment: Managing 4GL Applications and Chapter 2, "Application Security," in this manual. For more information on auditing privileges, see the "Configuring auditing privileges" section.

Application design considerations

For legacy applications that use the database _User table to authenticate users, you might not require any database configuration or coding changes to set up auditing security. Your existing usage of the User ID (-U)/Password (-P) or the SETUSERID function might be sufficient. This is especially true in a client/server configuration, where the client has direct access to the database and the application and database user are identical. However, note that where you connect to multiple databases, each database can generate auditing events associated with a different connection ID. If you want the auditing ID to be the same for all connected databases, you must be sure to authenticate the same database connection ID for each database.

If you want to use a single Progress session ID as your auditing ID, regardless of individual requirements for database connection and access authorization, set the following database options:

Use Application User Id for Auditing — Described in an earlier section, this tells the database to use the Progress session ID as the auditing ID.
Record Authenticated Client Sessions — This option ensures that client login session context for the Progress session ID is recorded as part of the audit trail. For more information on using client login sessions with auditing, see the "Managing audit event context" section.

To provide a Progress session ID for your application, add the 4GL code necessary to assert a Progress session ID using the client-principal object and the SECURITY-POLICY:SET-CLIENT( ) method. For more information, see Chapter 2, " Application Security."

Many legacy applications written prior to Release 10.1A use their own 4GL authentication systems to enforce a single application user ID. If you want to use this application user ID as your auditing ID, you can maintain your existing 4GL authentication code. However, you must, again, set the appropriate database options and add the 4GL code necessary to assert your application user ID as a Progress session ID using the client-principal object and the SECURITY-POLICY:SET-CLIENT( ) method, as described in the previous paragraphs.

If you are developing an n-tier application, especially one that conforms to the OpenEdge Reference Architecture (OERA), you must use the client-principal object and SECURITY-POLICY system handle to maintain the correct application user ID and auditing identity between application server clients and the AppServer. For more information, see Chapter 2, " Application Security."